<?php

namespace Wgx\Admin\Com\Crud;

use PhpYes\Entity\BaseEntity;

interface CrudUserInterface
{
    /**
     * 在 crud 执行 op 之前进行一些设置工作, $op = $crud->getOp()
     * op = listpage => $extra = null
     * op = editpage => $extra = [entity]
     * op = readpage => $extra = [entity]
     *
     * @param Crud $crud
     * @param mixed $extra - 打包了其他的参数, 没有任何其他参数的话就是 null
     */
    public function setForOp(Crud $crud, $extra);

    // public function setForGetListData(Crud $crud);
    // public function setForGetData(Crud $crud, BaseEntity $entity);
    // public function setForGetExport(Crud $crud);
    // public function setForCreate(Crud $crud, BaseEntity $entity, $data);
    // public function setForUpdate(Crud $crud, BaseEntity $entity, $data);
    // public function setForCreateOrUpdate(Crud $crud, BaseEntity $entity, $data); // 在 setForCreate|setForUpdate 之后被调用
    // public function setForDelete(Crud $crud, $id);

    /**
     * 使用 客户端请求服务器带过来的参数 build 一个 Wgx\PdoEx\QueryBuilder::select 可以使用的 $where 参数
     * @param array $params - 客户端请求服务器带过来的参数，可以是 url 的 query 部分带过来的，也可以是 body 部分带过来的
     * @return array|null - refer Wgx\PdoEx\QueryBuilder::select($where) 参数
     */
    public function buildWhereForGetListData($params);

    /**
     * 使用 客户端请求服务器带过来的 排序 fieldName 和 排序 direction build 一个 Wgx\PdoEx\QueryBuilder::select 可以使用的 $orderBy 参数
     * @param string $fieldName
     * @param string $direction - {1:asc, 0:desc}
     * @return array|null - refer Wgx\PdoEx\QueryBuilder::select($orderBy) 参数
     */
    public function buildOrderByForGetListData($fieldName, $direction);

    /**
     * @param Crud $crud
     * @param BaseEntity $entity - $entity = $crud->entityTpl->findById($id);
     * @param null|array $context
     * @return array|null
     */
    public function formatData(Crud $crud, BaseEntity $entity, $context = null);

    /**
     * $context.where : array|null - refer \Wgx\PdoEx\QueryBuilder::select 的 $where
     * $context.orderBy : array|null - refer \Wgx\PdoEx\QueryBuilder::select 的 $orderBy
     * $context.limit : int - 分页参数 limit
     * $context.offset :  int - 分页参数 offset
     * $context.total : int - 数据总条数
     *
     * @param Crud $crud
     * @param array $data
     * @param null|array $context - [where => $where, orderBy => $orderBy, limit => $limit, offset => $offset, total => $total, ...]
     * @return array|null
     */
    public function formatListData(Crud $crud, $data, $context = null);

    /**
     * throws Wgx\Admin\Com\Crud\InvalidFieldValueException 来指示某个字段的值设置的不正确
     * @param Crud $crud
     * @param BaseEntity $entity - $entity = $crud->entityTpl->newObject(); or $entity = $crud->entityTpl->findById($id);
     * @param array $data - 客户端提交到服务器的数据
     */
    public function createOrUpdate(Crud $crud, BaseEntity $entity, $data);

    /**
     * 有些地方不能直接删除数据, 需要做软删除
     * @param Crud $crud
     * @param int[] $ids
     */
    public function deleteByIds(Crud $crud, $ids);
}